home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 41 / Amiga Format CD41 (1999-06)(Future Publishing)(GB)[!][issue 1999-07].iso / -seriously_amiga- / comms / other / dlg_1_27 / docs / dlgrexx.doc < prev   
Text File  |  1999-04-19  |  7KB  |  190 lines
  1. Port commands are a subset of Resource Manager commands. They are used to open,
  2. activate, close, and gain ownership of DLG's communication ports.
  3.  
  4. Unless indicated otherwise, the commands will return a 0 for no error.
  5. Otherwise, the error code will come from this list:
  6.  
  7.    -2    Port already active
  8.             Don't activate the same port twice.
  9.  
  10.    -3    Port not active
  11.             Deactivation and locking requires an active port.
  12.  
  13.    -4    Port not locked
  14.             You'll see this if you used the wrong password or if you're
  15.             going for an "immediate" lock which fails.
  16.  
  17.    -5    ResMan not active
  18.             You'll get this if DLG's resource manager, ResMan, is not running.
  19.             This probably means you don't have DLG running, either.
  20.  
  21.    -6    Out of Memory
  22.  
  23.  
  24.  
  25. Parameters bracketed in brackets [ like this ] are optional.
  26.  
  27.  
  28.  
  29. NAME
  30.    ActivatePort
  31.  
  32.    Activate a port for use.
  33.  
  34. USAGE
  35.    ActivatePort ( Port, [ BGCommand ] )
  36.  
  37.       Port:       The name of the port that you want to activate. (string)
  38.  
  39.       BGCommand:  A background command that you want to launch upon port
  40.                   activation. This command should accomplish something useful,
  41.                   such as monitoring the port for incoming calls. DLG:Setup is
  42.                   usually used for regular ports; GETTY and TrapDoor are other
  43.                   popular choices. (optional) (string)
  44.  
  45. NOTES
  46.  
  47.  
  48.  
  49. NAME
  50.    DeactivatePort
  51.  
  52.    Remove a port from the list of active ports. The port must be active already.
  53.  
  54. USAGE
  55.    DeactivatePort ( Port, [ Password ] )
  56.  
  57.       Port:       The name of the port that you want to deactivate. (string)
  58.  
  59.       Password:   A password to use to lock the port.  If the port is not
  60.                   already locked with a password, you may leave this out and DLG
  61.                   will supply a password to use while deactivating. If the port
  62.                   has been previously locked with a password, you must supply
  63.                   the same password to get the port. (optional) (string)
  64.  
  65. NOTES
  66.  
  67.  
  68. NAME
  69.    FreePort
  70.  
  71.    Release the lock on a port. You must have already locked it for this to work.
  72.  
  73. USAGE
  74.    FreePort ( Port, [ Password ] )
  75.  
  76.       Port:       The name of the port that you want to release. (string)
  77.  
  78.       Password:   A password used to lock the port.  If the port was not locked
  79.                   with a password, you must leave this out. If the port has been
  80.                   previously locked with a password, you must supply the same
  81.                   password to get the port. (optional) (string)
  82.  
  83. NOTES
  84.  
  85.  
  86. NAME
  87.    ImmedLockPort
  88.  
  89.    Lock the specified port immediately.  If an immediate lock cannot be
  90.    achieved, it returns immediately with error code -4.
  91.  
  92. USAGE
  93.    ImmedLockPort ( Port, [ Password ], [ Reason ], [ Priority ], [ Break ] )
  94.  
  95.       Port:       The name of the port that you want to lock. (string)
  96.  
  97.       Password:   The password used to lock the port.  If you leave it blank,
  98.                   DLG will supply an internal password. (optional) (string)
  99.  
  100.       Reason:     While this doesn't affect functionality, giving a reason for
  101.                   the lock is helpful to users online at the time. (string)
  102.                   (optional)
  103.  
  104.       Priority    A value between -127 and 128 inclusive, indicating the
  105.                   priority of your lock. If two or more processes are trying to
  106.                   lock the same port, the one with the highest priority will get
  107.                   the lock. Defaults to 0. (numeric) (optional)
  108.  
  109.       Break       An external command that is used to break (interrupt) your
  110.                   process if another process locks the port with a higher
  111.                   priority. If the port is one that has a high level of
  112.                   contention, you should supply this command --otherwise, the
  113.                   system may lock up waiting for your program to release a port.
  114.  
  115. NOTES
  116.  
  117.  
  118. NAME
  119.    LockPort
  120.  
  121.    Lock the specified port, pending the lock until the port is free.
  122.  
  123. USAGE
  124.    LockPort ( Port, [ Password ], [ Reason ], [ Priority ], [ Break ] )
  125.  
  126.       Port:       The name of the port that you want to lock. (string)
  127.  
  128.       Password:   The password used to lock the port.  If you leave it blank,
  129.                   DLG will supply an internal password. (optional) (string)
  130.  
  131.       Reason:     While this doesn't affect functionality, giving a reason for
  132.                   the lock is helpful to users online at the time. (string)
  133.                   (optional)
  134.  
  135.       Priority    A value between -127 and 128 inclusive, indicating the
  136.                   priority of your lock. If two or more processes are trying to
  137.                   lock the same port, the one with the highest priority will get
  138.                   the lock. Defaults to 0. (numeric) (optional)
  139.  
  140.       Break       An external command that is used to break (interrupt) your
  141.                   process if another process locks the port with a higher
  142.                   priority. If the port is one that has a high level of
  143.                   contention, you should supply this command --otherwise, the
  144.                   system may lock up waiting for your program to release a port.
  145.  
  146. NOTES
  147.    This function will dwell until the port is available for lock. Use this
  148.    function only in places where you know that the port will be freed within a
  149.    reasonable amount of time.  If you are uncertain of this, and if you suspect
  150.    that your entire BBS will be locked up because of a pending lock, then use
  151.    ImmedLockPort instead -- that's what it's for.
  152.  
  153.  
  154. NAME
  155.    TransferPortLock
  156.  
  157.    Changes the status of a locked port.
  158.  
  159. USAGE
  160.    TransferPortLock ( Port, [ OldPassword ], [ NewPassword ], [ Reason ],
  161.                             [ Priority ], [ Break ] )
  162.  
  163.       Port:       The name of the port that you want to lock. (string)
  164.  
  165.      OldPassword: The password used to lock the port previously.  If you leave
  166.                   it blank, DLG will supply an internal password. (optional)
  167.                   (string)
  168.  
  169.      NewPassword: The new password to lock the port with.  If you
  170.                   leave it blank, DLG will supply an internal password.
  171.                   (optional) (string)
  172.  
  173.       Reason:     While this doesn't affect functionality, giving a reason for
  174.                   the lock is helpful to users online at the time. (string)
  175.                   (optional)
  176.  
  177.       Priority    A value between -127 and 128 inclusive, indicating the
  178.                   priority of your lock. If two or more processes are trying to
  179.                   lock the same port, the one with the highest priority will get
  180.                   the lock. Defaults to 0. (numeric) (optional)
  181.  
  182.       Break       An external command that is used to break (interrupt) your
  183.                   process if another process locks the port with a higher
  184.                   priority. If the port is one that has a high level of
  185.                   contention, you should supply this command --otherwise, the
  186.                   system may lock up waiting for your program to release a port.
  187.  
  188. NOTES
  189.  
  190.